Repository navigation
Stop discarding calls over values the caller never wrote - #292
Merged
hffmnnj merged 19 commits intoAug 5, 2026
Merged
Conversation
Tool-call serialization in some hosts injects empty strings the caller never
authored — into status fields, mode selectors, and nested task_updates[]
entries. An empty string is never a legitimate value for those fields but
arrives as a present value, defeating the caller's intent: a mode conflict
the caller never created, an "invalid status" rejection, or "" stored as a
real value. Wave 2 rewrote goop_write_wave's description to warn against
passing empty strings; the next agent still failed the same way, because the
empty string is injected below the level any description can reach.
Add a single shared boundary (shared/coalesce.ts) that treats an exact "" as
absent (omitted) for fields where empty has no legitimate meaning, applied in
createTools so it runs on BOTH the V1 and V2 registration paths from one
source of truth. Recurses through arrays and nested objects; only exact "" is
affected (null/undefined/0/false/[]/{} and whitespace-only strings pass
through untouched); a non-empty value is never dropped.
Exempt an explicit, audited set of fields where empty is a documented
operation (EMPTY_STRING_LOAD_BEARING_KEYS): new_string/old_string (patch
delete + patch-mode activation on ""), pr_url/pr_branch/title (clear the
stored value). content is deliberately not exempt — an injected content:""
would silently destroy a document; coalescing yields a loud none-mode error.
goop_write_wave gains minimal tolerance for a status coalesced to absent in
task_updates[]/task_update (skip the no-op entry rather than storing
undefined), matching the existing !== undefined guard pattern already used
for optional status fields.
Regression test reproduces the exact Wave 2 verifier failure shape —
{wave_number, status:"", task_updates:[{task_index:0,status:""}],
verifications:[...]} — and asserts it now succeeds and records the
verifications. Exclusion tests prove empty new_string still deletes, empty
old_string still activates patch mode, and empty pr_url/pr_branch/title still
clear.
Add an "Empty-string argument coalescing" subsection under the House Tool- Description Standard stating the behavior where callers will see it: what the boundary does, why it exists (descriptions cannot fix host-injected empties), the recursion contract, and the full exclusion table with the reason each exempt field's empty value is load-bearing (new_string/old_string delete and patch activation; pr_url/pr_branch/title clear). Notes that content is deliberately not exempt. Repin the prompt-audit byte-count and absolute-language assertions to the new true values (references 171,170 -> 174,047 bytes; totalAbsoluteHits 319 -> 326, +7 contract invariants in the new section), with deltas documented in the assertion comments. No assertion weakened or deleted.
…rect Callers can now pick the right read surface from the description alone: goop_read_db names the ADL trap (doc_type:adl returns 'No adl document found' because the ADL is structured events, not a document row) and redirects to goop_adl; goop_read_section states the separate-stores boundary so a caller knows a goop_write_db document is not visible here until a keyed section exists; goop_search_docs states that plural filters OR within each set (widening, not narrowing) and AND across types, eliminating the silent-wider-results surprise.
…st-try correct Callers can now rely on the full mode and rejection contract before any call. goop_write_db states all three modes (full/patch/batch) and the four rejected combinations, plus that an empty content coalesces to absent rather than wiping a document. goop_write_section adds the write/delete action dimension, the items[]-rejected-for-delete rule, and the _migrated-legacy-content reservation. goop_append_chronicle states plainly that cross-store atomicity is unavailable across chronicle/ADL/ memory, that an aux failure after chronicle success leaves the chronicle in place, and that the caller must retry the failed store separately. All six document tools leave PENDING_CONFORMANCE; the three multi-mode write tools enter HIGH_FRICTION_TOOLS because their rejection contracts cannot fit under 700 without dropping a rule a caller needs to avoid an error. Documentation and tests only; no runtime behavior changed.
…t-try correct Bring goop_save_note, goop_search_notes, goop_reference, goop_boot, goop_checkpoint, and goop_compact into conformance with the House Tool-Description Standard (references/tool-reference.md): named sections (WHEN TO USE / WHEN NOT TO USE / RETURNS), length bounds, recursive argument .describe() on every field including nested items[] element objects, and no empty-string-endorsing phrasing. - goop_save_note: create/patch/batch modes with cross-field rejection; documents that items[] is now atomic (historically non-atomic). Allowlisted at 766 chars by parity with goop_write_db (same multi-mode write shape). - goop_search_notes: documents the note_id escape hatch (bypasses ranking, returns full body) and the full/body_offset/body_limit window interaction. - goop_reference: documents the exact case-insensitive section-match rule and that a miss returns full content rather than failing. - goop_boot: adds .describe() to all 14 args; states documents load ONLY when doc_types is explicitly passed (no default set). - goop_checkpoint: action/id/context described; save/load require id. - goop_compact: states orchestrator-only, V1-only, next_step required and replayed as the resume action. Removes all six from PENDING_CONFORMANCE; adds goop_save_note to HIGH_FRICTION_TOOLS. Documentation and schema only; no runtime behavior changes.
Bring memory_save, memory_search, and memory_forget to the house tool-description standard and drop them from PENDING_CONFORMANCE (17 -> 14). memory_forget (allowlisted, 1074 chars): the destructive contract is now unmissable. Documents the two mutually exclusive modes (id deletes immediately and ignores confirm; query needs confirm:true), states plainly that the operation is irreversible, and calls out the footgun that the read-only preview caps at 20 rows while confirmed deletion searches up to 100. Added to HIGH_FRICTION_TOOLS with justification. memory_save (691 chars): documents what actually persists. Verifies the per-type importance defaults (decision 7, note 4, else 5) at the tool layer, the type=decision field-folding and fact auto-generation, the id -1 graceful-degradation signal, and the deduplicate:true reinforce-not-insert contract (importance=max(old,new), created_at refreshed, content unchanged, no new row). memory_search (695 chars): documents retrieval semantics honestly. Filters AND-combine; concepts OR within the list as a substring match; includeFieldNotes:true changes both membership and ranking via RRF (k=60) and applies filters to the memory side only. MH11/MH20 investigation: the 'query plus tag misses results that query alone finds' observation is the intended AND-combination contract, not a ranking bug. A record matching the query text but lacking the filter is excluded by design. Confirmed under real FTS5 and pinned at both the tool and manager levels. No algorithm change made or warranted. Tests added: - memory_forget: id precedence over query+confirm, confirm ignored on id path, query preview searches with limit 20, confirm-gates-query. - memory_save: failed write degrades to id -1 rather than throwing. - memory_search: limit clamp, empty-query no-results, concept filter narrows by design (tool level). - features/memory (real FTS5): concept filter excludes a query match lacking the concept; substring/case-insensitive tag matching; and forgetByQuery deletes 30 > the 20-row preview ceiling.
Bring goop_setup, goop_spec, goop_infer_intent, goop_status, goop_get_global_config, and slashcommand into conformance with the house tool-description standard (WHEN TO USE / WHEN NOT TO USE / RETURNS sections, recursive .describe() on every arg, length bounds). PENDING_CONFORMANCE: 14 → 8. Action-to-argument legality is now documented precisely for each tool: - goop_setup: every action mapped to which args it reads vs ignores; scope is declared but silently ignored by every action; gitignoreGoopspec applies as a cross-action side effect regardless of action. - goop_spec: file is read only by read; phase is ignored by all. - goop_infer_intent: autoApply vs autoRun documented as separate mechanisms with different confidence gates (0.85 hard floor + threshold default 0.9 vs 0.75 autoRun floor); below-threshold is never an error. - goop_status: verbose is declared but currently ignored. Allowlisted (HIGH_FRICTION_TOOLS): goop_setup (1169), goop_spec (841), goop_infer_intent (1152) — all carry mandatory mode/contract content that cannot fit under 700. Contract tests pin the three arguments-that-do-nothing (scope, phase, verbose) and action-dependent arg legality for goop_setup.
…y correct Bring ast_grep, difftastic, scip, background_command, background_status, and background_cancel into conformance with the house tool-description standard. Removes all six from PENDING_CONFORMANCE (8 -> 2); adds ast_grep, scip, and difftastic to HIGH_FRICTION_TOOLS with per-tool justifications. Each description now carries the mandatory WHEN TO USE / WHEN NOT TO USE / RETURNS sections plus MODES/CAVEATS where applicable, and every argument (including nested array item fields) carries a terminal .describe(). Key load-bearing content added: - ast_grep: documents the three modes (search / rewrite dry-run / rewrite apply) and the conditional no-op that apply:true without rewrite has no effect (-U is only appended inside the rewrite branch). - scip: documents the action-dependent required field (symbol required for definitions/references/implementations, ignored by index) and that each action resolves a different binary (scip vs scip-typescript). - difftastic: documents the alias-pair cross-field contract and the missing-binary-vs-no-differences distinction. - background_command: keeps the verified timeout default (1800s/30min), the integer [1,86400] range with reject-not-clamp, and the kill-on-expiry. - background_status: documents the lazy expiry sweep that marks timed-out without killing (eager timer owns the kill). - background_cancel: documents the process-group SIGTERM->SIGKILL escalation. No behavior changes; documentation and test-gate edits only.
…ORMANCE generate_image (allowlisted, 1136 chars): full house-standard rewrite — Purpose, WHEN TO USE/NOT TO USE, MODES (dryRun vs live), RETURNS, and CAVEATS covering the png-only transparency constraint (green-screen + local chromakey), default output path, count-suffix behavior, the OAuth/credits cost model, and two dead arguments. mask and outputCompression are declared on the schema but never read by execute() nor forwarded to buildBody() — documented as 'Declared but not read by the tool; supplying it has no effect.' Cross-field constraints surfaced on out, outputFormat, and background so callers see them before the call, not through a validation rejection. goop_create_pr (allowlisted, 904 chars): documents the terminology gate contract — scans title/body/branch, error-severity blocks while warn-severity proceeds, code spans masked in title/body but never in branch, reword-not-retry semantics with example rewrites. Dropped the misleading merge-method sentence; documented honestly that no merge-method argument is exposed and it is a repo setting on GitHub. goop_spec (tightened from 841 to 632 chars, removed from allowlist): the 3-action mode contract (file read only by read; phase ignored by all) fits under 700 when the per-action file-ignored clauses are collapsed into one. No contract lost. PENDING_CONFORMANCE is now empty: all 38 tools face every predicate. Full suite: 2690 pass, 0 fail.
The memory-save tool previously formatted decision rationale before passing it to the manager, which formatted the same fields again. Delegate content composition solely to the storage manager so persisted decision content and FTS weighting are not duplicated. Changes:\n- Pass raw decision content from the tool\n- Pin manager composition and tool delegation contracts
Several action-dispatch errors identified a missing field without showing a corrected request. Include the tool context and a valid retry shape so callers can recover without consulting implementation details. Changes:\n- Teach required state and blocker action payloads\n- Clarify memory deletion and setup reset confirmations
Reconcile secondary doc surfaces with what the code actually does so each fact has one owner (the emitted schema) rather than stale copies. AGENTS.md: - Record the build-vs-source deployment gap in Gotchas: package.json points main/exports at src/index.ts, but the build script emits a dist/index.js bundle and the host loads that bundle, once per session, from an install path outside this worktree. Source edits here do not affect the running session; validating a behavior change needs a rebuild plus restart, and unit tests are the only in-session evidence. - Fix the stale tool-factory count (30 -> 38), pinned by the registry tests; point at the emitted schema as the argument authority. - Replace the restated ast_grep/difftastic/scip/generate_image/ background_* argument and when-to-use lists with pointers to the emitted schemas. A restatement is a copy that silently goes stale; a prior version of this section fabricated model and inputFidelity args that generate_image never declared. tool-reference.md (the maintained cheat sheet): - Resolve two goop_write_wave contradictions that claimed verifications/traceability were 'not available alongside items batch mode'. They are supplied per-item inside each items[] entry; top-level side payloads alongside items[] are rejected, not dropped. - Remove the phantom generate_image model/inputFidelity args and note mask/outputCompression are declared but ignored (owned by the schema). prompt-audit test: - Repin references.bytes 174_506 -> 174_965 to the true measured value. totalAbsoluteHits unchanged at 328 (no must/never/always/critical/ only language added or removed).
Classify every registered tool for MODES and CAVEATS requirements so newly added tools cannot bypass the conditional section gate. Document the five additional mode-bearing tools and prove missing required conditional sections fail conformance.
Require mode sections for duplicate reinforcement, cross-store memory search, and draft pull-request creation. Document each opt-in path so callers can predict its execution and result.
Fix duplicated decision content and record the deployment gap
Arm the gate over all 38 tools
Say plainly which arguments do nothing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes the single largest source of failed tool calls in this codebase, then brings twelve more tools into conformance with the House Tool-Description Standard. Stacked on #291.
The behavior change
Agents calling these tools kept hitting rejections caused by arguments they never authored. A call meant as
{ wave_number: 3, verifications: [...] }would arrive as{ wave_number: 3, status: "", task_updates: [{ task_index: 0, status: "" }], verifications: [...] }. The tool then rejected it for a conflict the caller never created.This was fixed rather than documented because documenting it was tried first and measurably failed. #291 rewrote
goop_write_wave's description specifically to warn against passing empty strings. The very next agent to call that tool failed the same way and could not record its verification rows at all. An earlier one failed after being warned directly in its instructions. Five occurrences, two of them after the fix meant to prevent them.The reason is structural: the empty strings are introduced during call serialization, after the caller's intent is already gone. No description can reach that layer.
So the boundary now treats an exact empty string as absent, before any tool logic runs, on both the V1 and V2 host paths from one shared seam.
What is deliberately not coalesced
Some fields genuinely mean something when empty, and coalescing those would convert an intentional operation into a silent no-op — the exact defect class this change exists to eliminate. An empty
new_stringmeans delete this text; an emptypr_urlmeans clear the stored value.Exclusions are scoped by tool and field, not by field name. An audit caught the first attempt exempting
titleglobally, which would have let an empty title survive intomemory_saveandgoop_create_prwhere it means nothing. Tools not named in the policy get no exemption, so a future tool with atitleargument gets the safe default rather than silently inheriting one written for something else.contentwas considered and deliberately left unprotected: coalescing it produces a loud error, whereas protecting it would let an injected emptycontentsilently wipe a document.Only exact empty strings are affected.
null,undefined,0,false,[],{}, and whitespace-only strings pass through untouched, and the pass recurses into arrays and nested objects — every recorded failure involved an empty string nested inside an array element.Documentation
Twelve tools brought into conformance, taking the total from 9 to 21 of 38. The clarifications worth calling out:
goop_read_dbdocuments that"adl"is an accepteddoc_typethat can never resolve to a document, because that store holds an append-log of eventsgoop_search_docsdocuments that plural filters widen rather than narrow — they OR within a set and AND across setsgoop_append_chroniclestates plainly that its piggyback writes are not atomic across stores, and what to do when one succeeds and another failsgoop_bootstates that documents load only whendoc_typesis suppliedgoop_referencestates that section matching is exact, and that a miss returns the whole resource with a note rather than failingVerification
2670 pass, 0 fail; typecheck clean. Independently audited twice — the first audit rejected the
titlescoping, which is fixed here and re-verified.Correction
An earlier version of this description claimed that every agent session after the boundary landed reported no unauthored empty strings, offering that as the strongest evidence. That claim was wrong and is withdrawn.
The host loads this plugin from a built bundle at its install path and loads it once per session. The change in this branch is source in a worktree that was never built or deployed, so it has not executed in any session that reported on it. Those clean reports describe the old code. They were absence of evidence, and I read them as evidence.
What holds is the unit-level proof: the boundary is exercised directly, across both host paths, including the nested-in-array shape that caused the original failures, with the exclusion scoping pinned per tool.
What does not exist is end-to-end confirmation in a live host. That requires a rebuild at the install path and a restart, and it should be done before anyone relies on this being active.
The tell was a later agent being rejected over an injected empty string — impossible if the fix were live. Two independent audits passed this branch without catching it, because both reasoned about the source rather than asking which artifact the host was running.